home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / graphics / qrt.lzh / TECHMAN.DOC < prev    next >
Text File  |  1989-02-16  |  19KB  |  529 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.         
  8.         
  9.                              QRT Technical Reference
  10.         
  11.         
  12.         INTRODUCTION
  13.         
  14.         The QRT ray tracing system  has  been  designed  to make the code
  15.         easily maintainable and  expandable.   An  object oriented design
  16.         philosophy was used for the  program,  and the resulting code has
  17.         been made as robust as practical given time constraints.
  18.         
  19.         This document explains the design of QRT.  First, the function of
  20.         each QRT C file will be listed.    Next,  the QRT data structures
  21.         will  be  explained,   and   finally,   some   details   of  code
  22.         implementation discussed.
  23.         
  24.         
  25.         QRT C CODE FILES
  26.         
  27.         The QRT code is broken down  into  16 C files and 3 header files,
  28.         each containing a group of related  functions.  The files are, in
  29.         alphabetical order:
  30.         
  31.            FILE              FUNCTION                              
  32.         
  33.            bbox.c            bounding box intersection routines
  34.            error.c           error reporting routines
  35.            inout.c           recursive decent input parser
  36.            instance.c        file for INSTANCE primitives
  37.            intersect.c       object intersection routines
  38.            lexer.c           simple lexical analyzer
  39.            mth.c             vector math support
  40.            norm.c            normal finding functions for objects
  41.            offset.c          offsets a primitive by dx, dy, dz
  42.            pattern.c         finds pattern info for objects
  43.            patternio.c       auxiliary parser for patterns
  44.            precomp.c         pre-computes some info for objects
  45.            qrt.c             main routine and initialization code
  46.            ray.c             actual ray tracing algorithims
  47.            relpos.c          finds relative position on an object
  48.            resize.c          resize any primitive
  49.            stack.c           stack and object creation routines
  50.         
  51.            header.h          instantiations of some global variables
  52.            pattern.h         pattern info
  53.            qrt.h             data structure definitions
  54.         
  55.         
  56.         The function of each  group  of  routines  will  be  discussed in
  57.         greater detail in rest of this document.
  58.  
  59.  
  60.         QRT Ray Tracer               Page 1           Technical Reference
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.         
  74.         DATA STRUCTURES
  75.         
  76.         All QRT data  structures  are  defined  in  qrt.h.   This file is
  77.         broken down into sections, as follows:
  78.         
  79.          OBJECT TYPE DEFINITIONS:
  80.            C #define  statements  for  each  object  type  (sphere, lamp,
  81.            observer, etc).
  82.            
  83.          MISC DEFINES
  84.            Other #defines for screen size, etc.
  85.            
  86.          VECTOR data structure
  87.            A floating point 3-tuple vector definition.
  88.            
  89.          COLOR VECTOR data structure
  90.            A red,green,blue integer 3-tuple structure.
  91.            
  92.          COLOR INFO structure
  93.            This is an important structure. It lists color information for
  94.            an    object,    including    ambient    and   diffuse   light
  95.            characteristics,  reflection   and  transmission  data,  Phong
  96.            specular  reflection  coefficient,  index  of  refraction, and
  97.            object dithering data.
  98.            
  99.          PRECOMPUTE structure
  100.            This contains some fields which can be filled with precomputed
  101.            information before the  ray-tracing  is begun. This saves time
  102.            by eliminating redundant  calculations  for  every line/object
  103.            intersection.   The  use   of   these  fields  is  up  to  the
  104.            intersection routines.  Each  object  also  has a 'precompute'
  105.            routine which fills this structure.
  106.            
  107.          PATTERN structure
  108.            The  pattern  definition   structure  contains  a  color  info
  109.            structure.  It is used  to  change  the  characteristics  of a
  110.            primitive  object  over  the  surface  of  that  object.   For
  111.            example, checkered, brick, or tile patterns may be defined.
  112.            
  113.          OBJECT structure
  114.            The base structure of  QRT.   All  objects  are  defined as an
  115.            object structure.  This structure contains:
  116.            
  117.               A) A location vector for the object
  118.               B) 3 directional vectors
  119.               C) The object type flag
  120.               D) Some constants for QUADRATIC objects
  121.               E) A color info structure
  122.               F) Sibling and child pointers for the object tree
  123.               G) A pointer to a pattern structure
  124.  
  125.  
  126.         QRT Ray Tracer               Page 2           Technical Reference
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.               H) x and y multipliers for pattern sizing
  140.               I) A name field for the object
  141.            
  142.          WORLD structure
  143.            This structure contains all data about the world.  It contains
  144.            pointers to the object tree, the  lamp list, the observer, and
  145.            the sky, and the pattern  stack.   It  also contains statistic
  146.            information, such as  total  number  of  rays  traced, and the
  147.            output file name and pointer.
  148.            
  149.          OBJECT_DATA structure
  150.            The header.h file contains  an  array  of  this structure, one
  151.            array element per object type.   The structure itself contains
  152.            pointers to functions that perform  known operations on object
  153.            structures.  This design  allows  much cleaner code and easier
  154.            addition of object types.  The object function pointers are:
  155.            
  156.               ColTest:  Tests for object collisions
  157.            
  158.               FindNorm: Finds normal to surface at a given position
  159.            
  160.               FindBbox: Computes size of bounding box for object
  161.            
  162.               RelPos:   Finds relative position on object surface
  163.                         given a position in space
  164.            
  165.               PreComp:  Stuffs 'precomp' structure for each object
  166.                         before ray-tracing is begun.  The precomp and
  167.                         intersect routines must agree on the exact usage
  168.                         of the fields in this structure.
  169.            
  170.               Offset:   Moves a primitive by dx, dy, dz.  This is used
  171.                         for instances.
  172.            
  173.               Resize:   Resizes a primitive ( and scales its location
  174.                         vector).  This is also used for instances.
  175.            
  176.            This structure permits expressions such as:
  177.            
  178.               (*(ObjData[CurrObj->type].ColTest))(line,Currobj,&t);
  179.            
  180.            which means:
  181.            
  182.               (collision func for this obj type )(parameters);
  183.            
  184.            instead of a large case  statement.   Execution is faster, and
  185.            if new  objects  are  added,  the  code  does  not  have to be
  186.            changed.  If a  certain  operation  is  illegal  for a certain
  187.            object type, the ObjData  entry  points  to an Err() function.
  188.            This way, if something  goes  wrong,  execution  is terminated
  189.            gracefully instead of jumping to a random location in memory.
  190.  
  191.  
  192.         QRT Ray Tracer               Page 3           Technical Reference
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.            
  206.          MATH defines
  207.            MIN, MAX, SQRT, DotProd macros
  208.            
  209.          DEFAULT structure
  210.            Keeps default color information
  211.            
  212.          ERROR codes
  213.            Defines for all possible error conditions
  214.            
  215.          ROBUST flag
  216.            There are many sections of code of the form:
  217.            
  218.               # ifdef ROBUST
  219.                  code
  220.               # endif
  221.            
  222.            such that, if ROBUST is defined, the bounds-checking code will
  223.            be compiled.  It is recommended  that this flag be always set,
  224.            although SLIGHTLY faster execution is possible with it reset.
  225.            
  226.            
  227.         CODE DESCRIPTION
  228.         
  229.         The function of each section of  code  will  be described in more
  230.         detail here.
  231.         
  232.          BBOX.C
  233.            
  234.